Next: File Names, Previous: Information about Files, Up: Files [Contents][Index]
The functions in this section rename, copy, delete, link, and
set the modes (permissions) of files. They all signal a
file-error error if they fail to perform their
function, reporting the system-dependent error message that
describes the reason for the failure.
In the functions that have an argument newname, if a file by the name of newname already exists, the actions taken depend on the value of the argument ok-if-already-exists:
file-already-exists error if
ok-if-already-exists is nil.The next four commands all recursively follow symbolic links
at all levels of parent directories for their first argument,
but, if that argument is itself a symbolic link, then only
copy-file replaces it with its (recursive)
target.
This function gives the file named oldname the additional name newname. This means that newname becomes a new hard link to oldname.
In the first part of the following example, we list two files, foo and foo3.
$ ls -li fo* 81908 -rw-rw-rw- 1 rms rms 29 Aug 18 20:32 foo 84302 -rw-rw-rw- 1 rms rms 24 Aug 18 20:31 foo3
Now we create a hard link, by calling
add-name-to-file, then list the files again.
This shows two names for one file, foo and
foo2.
(add-name-to-file "foo" "foo2")
⇒ nil
$ ls -li fo* 81908 -rw-rw-rw- 2 rms rms 29 Aug 18 20:32 foo 81908 -rw-rw-rw- 2 rms rms 29 Aug 18 20:32 foo2 84302 -rw-rw-rw- 1 rms rms 24 Aug 18 20:31 foo3
Finally, we evaluate the following:
(add-name-to-file "foo" "foo3" t)
and list the files again. Now there are three names for one file: foo, foo2, and foo3. The old contents of foo3 are lost.
(add-name-to-file "foo1" "foo3")
⇒ nil
$ ls -li fo* 81908 -rw-rw-rw- 3 rms rms 29 Aug 18 20:32 foo 81908 -rw-rw-rw- 3 rms rms 29 Aug 18 20:32 foo2 81908 -rw-rw-rw- 3 rms rms 29 Aug 18 20:32 foo3
This function is meaningless on operating systems where multiple names for one file are not allowed. Some systems implement multiple names by copying the file instead.
See also file-nlinks in File
Attributes.
This command renames the file filename as newname.
If filename has additional names aside from
filename, it continues to have those names. In
fact, adding the name newname with
add-name-to-file and then deleting
filename has the same effect as renaming, aside
from momentary intermediate states.
This command copies the file oldname to newname. An error is signaled if oldname does not exist. If newname names a directory, it copies oldname into that directory, preserving its final name component.
If time is non-nil, then this
function gives the new file the same last-modified time that
the old one has. (This works on only some operating systems.)
If setting the time gets an error, copy-file
signals a file-date-error error. In an
interactive call, a prefix argument specifies a
non-nil value for time.
If argument preserve-uid-gid is
nil, we let the operating system decide the user
and group ownership of the new file (this is usually set to
the user running Emacs). If preserve-uid-gid is
non-nil, we attempt to copy the user and group
ownership of the file. This works only on some operating
systems, and only if you have the correct permissions to do
so.
If the optional argument preserve-permissions
is non-nil, this function copies the file modes
(or “permissions”) of oldname to
newname, as well as the Access Control List and
SELinux context (if any). See Information
about Files.
Otherwise, the file modes of newname are left
unchanged if it is an existing file, and set to those of
oldname, masked by the default file permissions
(see set-default-file-modes below), if
newname is to be newly created. The Access Control
List or SELinux context are not copied over in either
case.
This command makes a symbolic link to filename, named newname. This is like the shell command ‘ln -s filename newname’.
This function is not available on systems that don’t support symbolic links.
This command deletes the file filename. If the
file has multiple names, it continues to exist under the
other names. If filename is a symbolic link,
delete-file deletes only the symbolic link and
not its target (though it does follow symbolic links at all
levels of parent directories).
A suitable kind of file-error error is
signaled if the file does not exist, or is not deletable. (On
Unix and GNU/Linux, a file is deletable if its directory is
writable.)
If the optional argument trash is
non-nil and the variable
delete-by-moving-to-trash is
non-nil, this command moves the file into the
system Trash instead of deleting it. See
Miscellaneous File Operations in The GNU Emacs
Manual. When called interactively, trash is
t if no prefix argument is given, and
nil otherwise.
See also delete-directory in Create/Delete
Dirs.
This function sets the file mode (or permissions) of filename to mode. It recursively follows symbolic links at all levels for filename.
If called non-interactively, mode must be an integer. Only the lowest 12 bits of the integer are used; on most systems, only the lowest 9 bits are meaningful. You can use the Lisp construct for octal numbers to enter mode. For example,
(set-file-modes #o644)
specifies that the file should be readable and writable
for its owner, readable for group members, and readable for
all other users. See
File permissions in The GNU
Coreutils Manual, for a description of
mode bit specifications.
Interactively, mode is read from the minibuffer
using read-file-modes (see below), which lets
the user type in either an integer or a string representing
the permissions symbolically.
See File
Attributes, for the function file-modes,
which returns the permissions of a file.
This function sets the default permissions for new files
created by Emacs and its subprocesses. Every file created
with Emacs initially has these permissions, or a subset of
them (write-region will not grant execute
permissions even if the default file permissions allow
execution). On Unix and GNU/Linux, the default permissions
are given by the bitwise complement of the
‘umask’ value.
The argument mode should be an integer which
specifies the permissions, similar to
set-file-modes above. Only the lowest 9 bits are
meaningful.
The default file permissions have no effect when you save a modified version of an existing file; saving a file preserves its existing permissions.
This macro evaluates the body forms with the
default permissions for new files temporarily set to
modes (whose value is as for
set-file-modes above). When finished, it
restores the original default file permissions, and returns
the value of the last form in body.
This is useful for creating private files, for example.
This function returns the default file permissions, as an integer.
This function reads a set of file mode bits from the minibuffer. The first optional argument prompt specifies a non-default prompt. Second second optional argument base-file is the name of a file on whose permissions to base the mode bits that this function returns, if what the user types specifies mode bits relative to permissions of an existing file.
If user input represents an octal number, this function
returns that number. If it is a complete symbolic
specification of mode bits, as in "u=rwx", the
function converts it to the equivalent numeric value using
file-modes-symbolic-to-number and returns the
result. If the specification is relative, as in
"o+g", then the permissions on which the
specification is based are taken from the mode bits of
base-file. If base-file is omitted or
nil, the function uses 0 as the
base mode bits. The complete and relative specifications can
be combined, as in "u+r,g+rx,o+r,g-w". See
File permissions in The GNU
Coreutils Manual, for a description of
file mode specifications.
This function converts a symbolic file mode specification
in modes into the equivalent integer. If the
symbolic specification is based on an existing file, that
file’s mode bits are taken from the optional argument
base-modes; if that argument is omitted or
nil, it defaults to 0, i.e., no access rights at
all.
This function sets the access and modification times of
filename to time. The return value is
t if the times are successfully set, otherwise
it is nil. time defaults to the
current time and must be in the format returned by
current-time (see Time of Day).
This function sets the Emacs-recognized extended file
attributes for filename. The second argument
attribute-alist should be an alist of the same
form returned by file-extended-attributes. The
return value is t if the attributes are
successfully set, otherwise it is nil. See
Extended
Attributes.
This function sets the SELinux security context for
filename to context. The
context argument should be a list
(user role type
range), where each element is a string. See
Extended
Attributes.
The function returns t if it succeeds in
setting the SELinux context of filename. It
returns nil if the context was not set (e.g., if
SELinux is disabled, or if Emacs was compiled without SELinux
support).
This function sets the Access Control List for
filename to acl. The acl
argument should have the same form returned by the function
file-acl. See Extended
Attributes.
The function returns t if it successfully
sets the ACL of filename, nil
otherwise.
Next: File Names, Previous: Information about Files, Up: Files [Contents][Index]